home *** CD-ROM | disk | FTP | other *** search
/ C/C++ Users Group Library 1996 July / C-C++ Users Group Library July 1996.iso / vol_100 / 130_01 / yaccrl.doc < prev   
Text File  |  1985-03-09  |  8KB  |  192 lines
  1.  
  2. YACCRL.DOC
  3. ==========
  4.  
  5. **********************************************************
  6. *        Yet Another C CRL generator         *
  7. * This file contains information on using the "CCRL"     *
  8. * program to convert COM files (generated by ASM or MAC) *
  9. * into CRL format for use with the BDS C package.     *
  10. * The original program was called "CRLADD", and it was     *
  11. * written by:    Earl T. Cohen                 *
  12. *        Cyclotomics, Inc.             *
  13. *        2140 Shattuck Ave.             *
  14. *        Berkeley, Ca. 94704             *
  15. * Modifications and original documentation by:         *
  16. *        Jack M. Wierda                 *
  17. *        33 W. Naperville Rd. apt 9         *
  18. *        Westmont, Illinois 60559         *
  19. * This version (2) has been modified again to read a     *
  20. * listing file for the additional information required     *
  21. * by the CRL format (why not let the computer do the     *
  22. * work!), by:                         *
  23. *        Robert T. Pasky                 *
  24. *        36 Wiswall Road                 *
  25. *        Newton Centre, MA 02159             *
  26. **********************************************************
  27.  
  28. This program is another version of the CCRL program written by
  29. Earl T. Cohen, and modified by Jack M. Wierda.
  30.  
  31. The purpose of the program is to create a CRL-compatible file from
  32. an existing <filename>.COM and <filename>.PRN (or .LST) files. The
  33. <filename>.CRL  file  produced can then be manipulated using CLIB,
  34. putting it into the desired library (presently, only one  function
  35. is created at a time).
  36.  
  37. The audience for which this program is intended includes those who
  38. wish to create or modify C functions written in assembly  language
  39. but  do not have the MAC assembler for which "cmac.lib" performs a
  40. similar function. In fact, in my somewhat biased opinion, the CCRL
  41. method seems simpler and less artificial, if you can live with the
  42. fact that only one function is allowed per source file (something,
  43. by the way, which should not be difficult to surmount).
  44.  
  45. The command line is simply,
  46.  
  47.     CCRL <filename> [-p]
  48.  
  49. Where <filename> is the name of the .COM and .PRN file from  which
  50. the  CRL file will be created. The optional "-p" switch causes the
  51. program to display additional information, such as any lines  from
  52. the listing file containing relocatable code.
  53.  
  54. Using ASM or MAC (or any other compatible assembler) and  LOAD,  a
  55. .COM file should be created. At the same time, a listing file (for
  56. ASM and MAC this is a .PRN type file) will be created.
  57.  
  58. The .COM file is simply read to obtain a copy of the object  code.
  59. The  .PRN  file is a convenient way of finding the addresses which
  60. will require reloction. The external function names and  the  size
  61. of the object code is also obtained by reading the .PRN file.
  62.  
  63. In order for the program to "find" this information, a few special
  64. characters are introduced into the .PRN file.  Since these symbols
  65. are  placed  in the comment field, they can simply be added to the
  66. source (.ASM) file when it is created. This may seem like a lot of
  67. work, but it needs to be done only once. When any later changes or
  68. bug fixes are made to the function,  the relocation information is
  69. automatically updated, too.
  70.  
  71. The symbols are as follows:
  72.     ;#<function name> - function to be created
  73.     ;$<external required function name>
  74.             - as many other functions as necessary
  75.               and ended by:
  76.     ;$        - denotes end of required function list
  77.     ;'        - denotes internal relocation
  78.     ;"        - denotes external (function) call
  79.     ;#        - denotes end of function being created:
  80.               a line whose address field is one more
  81.               than the highest address of the function
  82.  
  83. The  above  symbols  are  listed in the order they should appear in
  84. the source file.  That is, the function name first, followed by the
  85. required function names  (one per line, as many as necessary).  The
  86. end of this list is indicated by a null function name (i.e., a ";$"
  87. followed by a new-line).  All this must appear  before  the  actual
  88. function code. The code, flagged with internal and external symbols
  89. where necessary, follows. Finally, the end of function (;#)  symbol
  90. must  appear at the end of the assembly code to be included in this
  91. function.
  92.  
  93.             -- Externals --
  94.  
  95. External function calls require special handling for the program to
  96. handle them properly.  The CRL format requires a JMP instruction at
  97. the beginning of the object code for each external function  called
  98. by this function.  (Their addresses are  filled  in by  CLINK  once
  99. their  actual locations are resolved.)  The calls made in your code
  100. must actually refer to whichever one of these JMPs  corresponds  to
  101. the  external function  (they will be assigned in the same order in
  102. which they appear in the external required  function  list. )  even
  103. even  though  the JMPs don't appear in the source code at all!  The
  104. best way to do this is to equate the function name.
  105.  
  106. The example below should make things a bit clearer.
  107.  
  108. TPA    EQU    100H    ;Start of transient program area
  109.     ORG    TPA
  110.             ;#foobar -- function name
  111. ABS    EQU    TPA+3    ;$abs
  112. PRINTF    EQU    TPA+6    ;$printf
  113.             ;$
  114.     ...
  115.     CALL    ABS    ;" This is an external function call
  116.     ...
  117.     LXI    H, MSG1    ;' This is an internal relocation
  118.     PUSH    H
  119.     CALL    PRINTF    ;" Another external function call
  120.     ...
  121. MSG1    DB    'Hello, there.'
  122.     END        ;#
  123.  
  124. Note that the constant added to the TPA is 3 * <location  of  name
  125. in e.r.f.n. list>, starting with 3 * 1 = 3.  I suggest you put the
  126. e.r.f.n. definitions on the same line -- don't forget  the  final,
  127. null definition!
  128.  
  129. The final symbol  (;#)  tells the program to stop reading the .PRN
  130. file and additionally indicates the end address for the function.
  131.  
  132.  
  133.             -- Relocation Symbols --
  134.  
  135. The internal and exteral relocation  symbols should appear on  any
  136. line  containing  an address which would be changed as the code is
  137. relocated by CLINK.  This means JMPs, CALLs, LHLDs and SHLDs. Also
  138. LXIs and DWs only if their operands are addresses to be relocated.
  139.  
  140. You should be aware that the actual relocation is done to the  2nd
  141. and  3rd bytes of the instruction on the line.  If you need to use
  142. DWs or are using a Z-80 four-byte instruction  (e.g., LD IX,@addr)
  143. this would cause the wrong bytes to be changed.  Therefore,  a "+"
  144. or  "-"  sign may follow the relocation symbols to add or subtract
  145. one from the address which is normally assumed. Use the minus sign
  146. (;'-) for DWs, and plus sign (;'+) for four-byte instructions.
  147.  
  148. Once these additions are made to the source file,  simply assemble
  149. it as you normally would;  the listing being sent to a disk  file.
  150. Use LOAD to create a .COM file.  Run this program,  and bingo! ...
  151. instant .CRL file!
  152.  
  153. --------------------------------------------------------------------
  154.  
  155. For those who wish to modify or simply understand this program, here
  156. is some additional inside information.
  157.  
  158. The .PRN file is read a line at a time, scanned for a semi-colon (;),
  159. and then the immediate next character is tested for whichever special
  160. symbols are expected. In the case of function names, any white space
  161. following the special symbol is skipped and the next 8 or fewer
  162. characters are converted to upper case and the last character has its
  163. high-order bit set to one as required by the CRL format. The name ends
  164. with the first white space following the first real character so that
  165. comments may be included on the same line.
  166.  
  167. When relocation symbols are found, the next character is checked for
  168. "+" or "-", which sets up a fudge factor of +1 or -1, otherwise it's 0.
  169. The line is scanned again for 4 hex digits starting at the LIST_COL
  170. column. This column is the address field for the instruction on that line.
  171. If your assembler listing has a different format, simply change the
  172. LIST_COL definition in the program and recompile. If your assembler uses
  173. split octal or some other format, some simple changes to the "readhx"
  174. function will be required.
  175.  
  176. When the end symbol (;#) is found, the address field is used to
  177. determine the size of the object file, which is used for several
  178. purposes (the number of bytes to read from the .COM file, for one
  179. thing).
  180.  
  181. Another change which may be necessary for other assemblers is the
  182. definition of LIST_BEGIN. This is simply the column of the listing
  183. file which begins the source text; it speeds up the scanning process
  184. by skipping past the line number, address and object code columns.
  185.  
  186. If you would like to try adding multiple functions per file, most of the
  187. routines which handle the output to CRL f